home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / Swap.man < prev    next >
Encoding:
Text File  |  1989-11-28  |  5.5 KB  |  134 lines
  1. ' $Header: /sprite/src/lib/c/etc/RCS/Swap.man,v 1.2 89/11/27 17:34:25 douglis Exp $ SPRITE (Berkeley)
  2. .so \*(]ltmac.sprite
  3. .HS Swap lib
  4. .BS
  5. .SH NAME
  6. Swap_Buffer \- Do byte-swapping and alignment of data buffers
  7. .br
  8. Swap_BufSize \- Calculate the necessary buffer size to hold swapped and aligned data
  9. .SH SYNOPSIS
  10. \fB#include <swapBuffer.h>\fR
  11. .sp
  12. void
  13. \fBSwap_Buffer\fR(\fIinBuf, inSize, inType, outType, format, outBuf, outSizePtr\fR)
  14. .sp
  15. void
  16. \fBSwap_BufSize\fR(\fIinBuf, inSize, inType, outType, format, outSizePtr\fR)
  17. .SH ARGUMENTS
  18. .AS Option *optionArray
  19. .AP char *inBuf in
  20. In-coming data buffer
  21. .AP int inSize in
  22. Size in bytes of inBuf
  23. .AP int inType in
  24. Type of byte-order and alignment of data in inBuf
  25. .AP int outType in
  26. Type of byte-order and alignment of data in outBuf
  27. .AP char *format in
  28. String describing format of data in inBuf (see below for more details)
  29. .AP char *outBuf out
  30. Buffer in which to put out-going swapped and aligned data
  31. .AP int *outSizePtr in/out
  32. outSizePtr is an in/out parameter for \fBSwap_Buffer()\fR, but just an out
  33. parameter for \fBSwap_BufSize()\fR.  See below for its use in \fBSwap_Buffer()\fR and
  34. \fBSwap_BufSize()\fR.
  35. .BE
  36. .SH DESCRIPTION
  37. .PP
  38. These routines are obsolete.  See \fbFmt\fR instead.
  39. .PP
  40. \fBSwap_Buffer()\fR takes a buffer of data (\fIinBuf\fR) from one machine byte-order
  41. and alignment type (\fIinType\fR) and produces an output buffer (\fIoutBuf\fR)
  42. of the same data swapped and aligned
  43. to conform to a different machine byte-order and alignment type (\fIoutType\fR).
  44. The parameter \fIoutSizePtr\fR is an in/out parameter to \fBSwap_Buffer()\fR.
  45. In a call to \fBSwap_Buffer()\fR, \fI*outSizePtr\fR should contain the size in bytes
  46. of the buffer parameter \fIoutBuf\fR.  As \fBSwap_Buffer()\fR
  47. returns, \fI*outSizePtr\fR
  48. contains the actual size of the swapped and aligned data.  If the return value
  49. of \fI*outSizePtr\fR is larger than its input value, then \fBSwap_Buffer()\fR needed
  50. more buffer space for the out-going data than \fIoutBuf\fR provided.  In this
  51. case, \fBSwap_Buffer()\fR stops swapping the data and instead calculates the amount
  52. of space in bytes that it needs.   It returns that value in \fI*outSizePtr\fR.
  53. If \fI*outSizePtr\fR returns with a 0 value, then an error occurred, such
  54. as the \fIformat\fR argument contained unrecognizable characters or contained
  55. a '*' character in a position other than the last character (see description
  56. of format string, below), or the sizes of the \fIformat\fR string or \fIinBuf\fR
  57. weren't compatible.  In the case of an error,
  58. if \fBSwap_Buffer()\fR is called from a user process, it will
  59. panic with an error string explaining the problem.  If called in the kernel,
  60. it will print a warning-level system error message and return.
  61. .PP
  62. \fBSwap_BufSize()\fR calculates the size required for the \fIoutBuf\fR parameter
  63. to \fBSwap_Buffer()\fR given the same input data (\fIinBuf\fR), byte-ordering
  64. types (\fIinType\fR and \fIoutType\fR), and the same data
  65. format (\fIformat\fR).  It returns this calculated value in \fI*outSizePtr\fR.
  66. If *outSizePtr returns with a zero, then an error occurred.  (See the errors
  67. listed above for \fBSwap_Buffer()\fR for details.)
  68. Different machines have different alignment (and thus padding) requirements,
  69. and this is why the size of the out-going data may be different from the
  70. size of the in-coming data.
  71. .PP
  72. The format
  73. string (\fIformat\fR) must describe the configuration of the data in
  74. the input buffer, \fIinBuf\fR.  The
  75. data can contain bytes, half-words (4 bytes), words (8 bytes) and double-words
  76. (16 bytes).
  77. .PP
  78. The format string describes these data
  79. types as follows:
  80. .IP "'b'"
  81. The character 'b' stands for a byte value (1 byte).
  82. .IP "'h'"
  83. The character 'h' stands for a half-word (2 bytes).
  84. .IP "'w'"
  85. The character 'w' stands for a word (4 bytes).
  86. .IP "'d'"
  87. The character 'd' stands for a double-word (8 bytes and not yet implemented).
  88. .IP "'0'-'9'*"
  89. A number in ascii means that the previous value type ('b, 'h', 'w', or 'd')
  90. is repeated the given number
  91. of times.  For instance, the string "w88" means that inBuf contains
  92. 88 word values in a row.
  93. .IP "\'*'"
  94. A '*' character means 1 or more occurrences of the previous value type.
  95. A '*' can only appear at the end of a format string, since otherwise there's no
  96. way to determine the actual number of repetitions of the previous value.
  97. .PP
  98. An example format string, "bwwh3w5b*", would describe a buffer
  99. containing the structure
  100. .DS
  101. .ta 1c 2c 3c 4c 5c 6c
  102.     struct    flea    {
  103.         char    mite;
  104.         int        spider;
  105.         int        worm;
  106.         short    moth;
  107.         short    mosquito;
  108.         short    beetle;
  109.         int        fly[5];
  110.         char    gnat[50];
  111.     };
  112. .DE
  113. .LP
  114. The machine byte-order and alignment types are defined in swapBuffer.h.
  115. Their names may change since complaints have been registered about the
  116. current names, but currently the types are as follows:
  117. .IP "\fBSWAP_SUN_TYPE\fR"
  118. The byte-ordering and alignment of 68020's.  Looking at an integer as if
  119. it were an array of 4 bytes (char buf[4]), buf[0] contains the low byte,
  120. buf[3] contains the high byte, and half-words and words are aligned
  121. to half-word boundaries.
  122. .IP "\fBSWAP_VAX_TYPE\fR"
  123. The byte-ordering and alignment of Vaxen.  Looking at an integer as if
  124. it were an array of 4 bytes (char buf[4]), buf[0] contains the high byte,
  125. buf[3] contains the low byte, and half-words and words are aligned
  126. to half-word boundaries.
  127. .IP "\fBSWAP_SPUR_TYPE\fR"
  128. The byte-ordering and alignment of the Spur machine.  Looking at an integer
  129. as if it were an array of 4 bytes (char buf[4]), buf[0] contains the high byte,
  130. buf[3] contains the low byte.  Half-words are half-word aligned and
  131. words are word aligned.
  132. .SH KEYWORDS
  133. byte-order, byte-swap, padding, alignment
  134.